cPanel/WHM Username-based Authentication

This method allows you to filter emails via our Outgoing filter, while using SMTP user authentication.

Basic Configuration

The BASIC setup relays all outgoing mail through SpamExperts using username-based authentication. It ensures outbound messages are sent securely and supports DKIM signing for domains with DKIM keys. This configuration is simple to implement and suitable for most standard cPanel/WHM environments where advanced forwarding or sender rewriting is not required.

1. Log in to Spam Experts, ensure the User is added as an authenticating method by following the Add an Outgoing User > Authenticating User instructions
   1. When adding the Authenticating User, ensure the correct limits are set matching your traffic volumes
2. Open WHM and navigate to the Exim Configuration Editor
3. Select Advanced Editor
4. Add the following to the POSTMAILCOUNT section:

smarthost_dkim:
  driver = manualroute
  domains = !+local_domains
  require_files = "+/var/cpanel/domain_keys/private/${lookup{$sender_address_domain}dsearch{/var/cpanel/domain_keys/private/}}"
  # Exclude null sender messages from relaying via the smarthost
  condition = ${if or {{!eq{$sender_address}{}} {!eq{$sender_host_address}{}}}}
  transport = remote_smtp_smart_dkim
  route_list = $domain SMARTHOST::587
 
smarthost_regular:
  driver = manualroute
  domains = !+local_domains
  # Exclude null sender messages from relaying via the smarthost
  condition = ${if or {{!eq{$sender_address}{}} {!eq{$sender_host_address}{}}}}
  transport = remote_smtp_smart_regular
  route_list = $domain SMARTHOST::587 

Replace SMARTHOST with the your SMTP hostname

5. Add the following to the TRANSPORTSTART section:

remote_smtp_smart_dkim:
  driver = smtp
  hosts_require_tls = *
  interface = ${if exists {/etc/mailips}{${lookup{$sender_address_domain}lsearch*{/etc/mailips}{$value}{}}}{}}
  helo_data = ${if exists {/etc/mailhelo}{${lookup{$sender_address_domain}lsearch*{/etc/mailhelo}{$value}{$primary_hostname}}}{$primary_hostname}}
  dkim_domain = $sender_address_domain
  dkim_selector = default
  dkim_private_key = "/var/cpanel/domain_keys/private/${lookup{$dkim_domain}dsearch{/var/cpanel/domain_keys/private/}}"
  dkim_canon = relaxed
  headers_add = "${perl{check_mail_permissions_headers}}"
  hosts_require_auth = *

remote_smtp_smart_regular:
  driver = smtp
  hosts_require_tls = *
  interface = ${if exists {/etc/mailips}{${lookup{$sender_address_domain}lsearch*{/etc/mailips}{$value}{}}}{}}
  helo_data = ${if exists {/etc/mailhelo}{${lookup{$sender_address_domain}lsearch*{/etc/mailhelo}{$value}{$primary_hostname}}}{$primary_hostname}}
  headers_add = "${perl{check_mail_permissions_headers}}"
  hosts_require_auth = * 

6. Add the following to the AUTH section:

SpamExperts_login:
  driver = plaintext
  public_name = LOGIN
  client_send = : username@demo-domain.invalid : yourUserPassword

Replace username@demo-domain.invalid with your username, and YourUserPassword with your password

Please ensure any special characters in the password required are escaped.

7. Save and restart
8. Make sure that you Allow list all your Spam Experts IPs, or add the Spam Experts hostname (spf.antispamcloud.com) to the following location:

Exim Configuration Manager > Basic Editor > Access Lists > "Only-Verify-Recipient".

Advanced Configuration

The ADVANCED setup provides enhanced handling for complex mail flows. It supports DKIM signing for outbound mail and uses SRS (Sender Rewriting Scheme) for forwarded messages, preventing SPF failures when forwarding mail. This configuration is recommended for environments where mail forwarding is common or where maximum deliverability and compliance with modern email authentication standards are required.

Please ensure that the SRSENABLED variable is enabled in your Exim configuration. If it is missing or incorrectly configured, the SRS functionality will not work.
Navigate to Home -> Service Configuration -> Exim Configuration Manager -> Basic Editor and look for Enable Sender Rewriting Scheme (SRS) Support: On.

Please follow the steps (Step 1 - Step 3) as stated in the Basic Configuration section.

4. Add the following to the POSTMAILCOUNT section:
   

   ######################################################################################
   # POSTMAILCOUNT
   # BEGIN: SpamExperts - Smarthost routing for ALL domains
   
   # Router 1: Handles unauthenticated forwards for ALL domains.
   smarthost_forwards:
     driver = manualroute
     condition = ${if and {{def:original_domain}{!def:sender_host_authenticated}}}
     .ifdef SRSENABLED
       transport = spamexperts_outbound_srs_smtp
     .else
       transport = spamexperts_outbound_smtp
     .endif
     domains = !+local_domains
     route_list = $domain SMARTHOST::587  
     no_more
   
   # Router 2: Handles direct sends and authenticated forwards for ALL domains that have DKIM.
   # Excludes null sender messages.
   smarthost_direct_dkim: 
     driver = manualroute
     condition = ${if and { \
       {eq{${perl{sender_domain_can_dkim_sign}}}{1}} \
       {or {{!eq{$sender_address}{}} {!eq{$sender_host_address}{}}}} \
      }}
     transport = spamexperts_outbound_smtp
     domains = !+local_domains
     route_list = $domain SMARTHOST::587
     no_more
   
   # Router 3: Handles all remaining outbound mail for ALL domains.
   # Excludes null sender messages.
   smarthost_direct_regular:
     driver = manualroute
     condition = ${if or {{!eq{$sender_address}{}} {!eq{$sender_host_address}{}}}}
     transport = spamexperts_outbound_smtp
     domains = !+local_domains
     route_list = $domain SMARTHOST::587
     no_more
   
   # END: SpamExperts - Smarthost routing for ALL domains
   ######################################################################################
   
   

   Replace the SMARTHOST in the POSTMAILCOUNT configurations with SpamExperts cluster hostname.

5. Add the following to the TRANSPORTSTART section:
   

   ######################################################################################
   # TRANSPORTSTART
   # BEGIN: SpamExperts - Smarthost Transports (Username Auth)
   
   
   # Transport 1: Handles direct sends and authenticated forwards requiring DKIM signing.
   spamexperts_outbound_smtp:
     driver = smtp 
     hosts_require_tls = *
     hosts_require_auth = *
     # Use a dedicated outbound IP if one is configured in /etc/mailips.
     interface = ${if exists {/etc/mailips}{${lookup{$sender_address_domain}lsearch*{/etc/mailips}{$value}{}}}{}}
     # Use a custom HELO name if one is configured in /etc/mailhelo.
     helo_data = ${if exists {/etc/mailhelo}{${lookup{$sender_address_domain}lsearch*{/etc/mailhelo}{$value}{$primary_hostname}}}{$primary_hostname}}
     headers_add = "${perl{check_mail_permissions_headers}}"
     dkim_domain = ${perl{get_dkim_domain}}
     dkim_selector = default
     # This provides the private key ONLY if it exists.
     # If a domain has no DKIM key, this returns empty.
     dkim_private_key = ${if exists{/var/cpanel/domain_keys/private/${dkim_domain}}{/var/cpanel/domain_keys/private/${dkim_domain}}{}}
     dkim_canon = relaxed
     dkim_strict = 0
   
   # Transport 2: Handles unauthenticated forwards requiring SRS rewriting.
   spamexperts_outbound_srs_smtp:
     driver = smtp
     hosts_require_tls = *
     hosts_require_auth = *
     interface = ${if exists {/etc/mailips}{${lookup{$original_domain}lsearch*{/etc/mailips}{$value}{}}}{}}
     helo_data = ${if exists {/etc/mailhelo}{${lookup{$original_domain}lsearch*{/etc/mailhelo}{$value}{$primary_hostname}}}{$primary_hostname}}
     headers_add = "${perl{check_mail_permissions_headers}}"
     # This block rewrites the Return-Path using the SRS secret key defined
     # by cPanel. This is the core of the SRS fix.
     .ifdef SRSENABLED
       return_path = ${srs_encode {SRS_SECRET} {$return_path} {$original_domain}}
     .endif
     # Note: This transport omits DKIM settings, as you cannot
     # validly sign a forwarded message on behalf of the original domain.
   
   # END: SpamExperts - Smarthost Transports (Username Auth)
   ######################################################################################
   

Please follow the rest of the steps (Step 6 - Step 8) as stated in the Basic Configuration section.

Disclaimer: This documentation may contain references to third party software or websites. N-able has no control over third party software or content and is not responsible for the availability, security, or operation, of any third-party software. If you decide to utilize a release involving third-party software, you do so entirely at your own risk and subject to the applicable third party’s terms and conditions of the use of such software. No information obtained by you from N-able or this documentation shall create any warranty for such software.